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1 .  Introduction 


This  document  outlines  the  procedures  for  installing  the  SQL  Ada  Module  Extensions  (SAME) 
standard  packages.  It  assumes  that  the  source  of  these  packages  has  been  off-loaded  from  the 
distribution  medium  to  a  machine  with  the  desired  Ada  compiler.  (A  description  of  the  distribution 
medium  accompanies  the  medium.) 

Installing  the  SAME  standard  packages  is  a  two-step  operation.  First,  a  subset  of  the  source 
must  modified;  second,  the  source  is  compiled  into  the  proper  Ada  library  or  libraries. 


2.  Modifying  the  Source 

There  are  six  files  on  the  distribution  medium  which  need  to  be  modified  before  compilation. 
These  files  are: 

1 .  SQL_Standard  (a  package  specification) 

2.  SQL_System  (a  package  specification) 

3.  SQL_Communications_Pkg_Body  (a  package  body) 

4.  SQL_Database_Error_Pkg_Body  (a  package  body) 

5.  To_String  (a  subunit  body) 

6.  To_SQL_Char_Not_Null  (a  subunit  body) 

2.1.  SQL_Standard  and  SQL_System 

The  packages  SQL.Standard  and  SQL_System  (see  Figures  1  and  2)  contain  type  definitions 
and  constants  that  describe  the  DBMS  to  the  SAME.  Strictly  speaking,  the  package 
SQL_Standard  is  part  of  the  ANSI  SQL  standard.  The  type  and  subtype  definitions  in 
SQL_Standard  describe  the  standard  ANSI  database  types  INT,  SMALLINT,  REAL,  DOUBLE 
PRECISION,  and  CHAR. 

The  information  needed  to  describe  the  numeric  types  can  be  found  in  the  documentation  sup¬ 
plied  by  the  DBMS  vendor.  If,  for  example,  the  DBMS  data  type  INTEGER  (or  INT)  references 
32-bit  integers,  and  SMALLINT  references  16-bit  integers,  these  type  definitions  should  be: 

type  int  Is  range  -(2**3i)  ..  (2**3i)  -  i; 
type  Smallint  iS  range  -(2**15)  ..  (2**15)  -  l; 

The  treatment  of  character  data  in  SQL_Standard  is  meant  to  support  the  character  sets  defined 
by  the  implementor.  If  the  DBMS  character  set  is  ASCII,  then  the  definitions  in  SQL_Standard 
should  read: 

package  Character_Set  renames  standard; 

subtype  Character_Type  Is  Character_^Set. Character ; 

Otherwise,  it  is  assumed  there  exists  an  Ada  package  that  supports  the  DBMS  character  set  for 
Ada  programs.  Assuming  that  that  package  is  called  Host_Character_Support_Pkg,  and  that  the 
character  enumeration  type  definition  within  that  pad<age  is  named  Character,  the  above  defini¬ 
tions  should  read: 
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package  Character__Set  renames  Host__Charactar_Support_P]cg; 
subtype  Charactar_Typa  Is  Character^Sat .Charactar; 

The  package  SQL_System  declares  two  constants  whose  values  cannot  be  deduced  from  the 
information  in  SQL_Standard.  The  constant  MAXCHRLEN  is  the  length  of  the  longest  string  the 
DBMS  will  store.  This  value  must  be  in  the  range  of  the  Ada  predefined  type  Standard. Integer  for 
the  target  compiler.  The  constant  MAXERRLEN  is  the  length  of  the  longest  error  message  the 
DBMS  error  message  routine  will  produce.  This  error  message  routine  or  function,  which  is  not 
controlled  by  the  ANSI  standard,  varies  from  DBMS  to  DBMS.  The  value  of  MAXERRLEN  must 
not  exceed  MAXCHRLEN.  Setting  MAXERRLEN  to  MAXCHRLEN  will  usually  work,  but  may 
waste  space. 

Note  Well:  The  packages  SQL_Standard  and  SQL_System  are  basic  to  every  SAME  application. 
Recompilation  of  these  packages  necessitates  recompilation  of  every  SAME  standard  package 
and  application.  It  is  imperative  that  the  values  in  these  padtages  be  correctly  set. 

package  Sql_Standar<l  Is 

package  character__set  renames  cap; 

subtype  Character_Type  Is  Character_Set.cst; 
type  Char  Is  array  (poaitiva  range  <» 
of  Character_Type; 
type  smaiiint  Is  range  b8..ts; 
type  int  Is  range  bi..ti; 
type  Real  is  digits  dr; 
type  Double  Precision  IS  digits  dd; 

—  type  Decimal  Is  to  be  determined; 
type  Sqlcode_^Type  Is range  bsc..tsc; 
subtype  Sql__Error  Is  Sqlcode_^Type 
range  sqicodejrype' first  -i; 

subtype  Not_Found  Is  Sqlcode_Type 
range  lOO. .100; 
subtype  Zndlcator_Type  Is  t; 

cap  la  an  implementor-defined  package  and  cat  la  an 
implementor-defined  character  type,  bs,  ts,  bi,  tl,  dr, 
dd,  bsc,  and  tsc  are  Inpl^nentor-deflned  Integral  values, 
t  la  Int  or  smalllnt  corresponding  t'*  an 
implementor-defined  <exact  nvimeric  type>  of  Indicator 
parameters . 

end  sql_standard; 

Figure  1:  The  Package  SQL_Standard 

2.2.  SQL_Communications_Pkg  and  SQL_Database_Error_Pkg 

The  packages  SQL_Communications_Pkg  and  SQL_Database_Error_Pkg  are  used  for  SAME 
standard  error  processing.  {See  the  document  Guidelines  for  the  Use  of  the  SAME, 
CMU/SEI-89-TR-16,  for  details.)  The  installation  of  these  packages  may  require  modifying  their 
bodies.  Modification  of  the  specifications  of  these  packages  is  not  generally  required.  The  body 
of  SQL_Communications_Pkg  will  depend  on  the  platform,  that  is,  the  Ada  compiler  and  DBMS. 
The  body  of  SQL_Database_Error_Pkg  is  independent  of  the  platform  but  dependent  on  deci¬ 
sions  to  be  made  at  installation  time. 
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—  SQL_System  Is  a  "platform-specific"  package 
within  the  SAME 
package  SQL_System  Is 

—  MAXCHRLEM  is  the  upper  bound  of  the  SQL_Char_Pkg 

subtypes  SQL_Char_Length  and  SQL_Unpadded_Length 
—  SQL_Char_Length  is  a  subtype  of  Natural  with  a  lower 
bound  of  1 

—  SQL_Unpadded_Length  is  a  subtype  of  Natural  with  a  lower 
bound  of  0 

MAXCHRLEN  :  constant  integer  str_leng; 

—  MAXERRZiEN  is  the  maximum  length  of  the  error  message 

string  returned  from  the  DBMS  error  message  function 

MAXERRLEN  :  constant  integer  :=  msg_leng; 

end  SQL_System; 

Flgure  2:  The  Package  SQL_System 

The  package  SQL_Database_Error_Pkg  declares  the  procedure  Process_Database_Error.  This 
procedure  is  called  by  abstract  module  procedures  when  an  unexpected  DBMS  exceptional  con¬ 
dition  (non-zero  SQLCODE  value)  has  occurred.  The  procedure  should  take  whatever  action  is 
mandated  by  local  policy  for  error  reporting.  The  exception  SQL_Database_Error,  defined  in 
SQL_Communications_Pkg,  will  be  raised  upon  termination  of  Process_Database_Error. 

The  distributed  version  of  Process_Database_Error  calls  the  function 
SQL_Database_Error_Message  in  package  SQL_Communications_Pkg,  which  returns  an  ex¬ 
planatory  error  message  acquired  from  the  DBMS.  It  then  prints  the  message  with  textjo.put. 
The  installer  should  modify  this  body  as  appropriate  for  his  or  her  installation. 

2.3.  To_Strlng  and  To_SQL_Char_Not_Null 

The  subunits  To_String  and  To_SQL_Char_Not_Null  are  used  for  converting  character  represen¬ 
tations.  If  the  DBMS  character  set  is  ASCII,  the  distributed  versions  of  these  subunits  can  be 
used  without  modification. 

Assume  that  is  not  the  case.  Assume  further  the  package  Host_Character_Support_Pkg  men¬ 
tioned  earlier  contains  route. es  for  converting  between  its  string  type,  Host_String,  a  one  dimen¬ 
sional  array  over  the  type  Host_Character_Support_Pkg.Character,  and  the  Ada  predefined  type 
Standard.String.  Specifically,  suppose  that  within  the  support  package  are  to  be  found  functions 
with  the  following  declarations: 

function  To_Stxlng  (Valu*  ;  Host_Strlng}  return  String; 
function  To_Host_Strlng  (Value  :  String)  return  Host_Strlng; 

In  that  case,  these  subunits  could  be  recoded  as  follows: 
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with  Ho8t._Charactttr_Support_P]cg; 
separate  (SQLjCharJPlcg) 

function  To_St'ring“"(Value  :  SQL_Char_Not_Null) 
return  string  Is 

package  HCSP  renames  Ho8t_Charactar_Support_Pkg; 
begin  “ 

return  (HCSP  .  To_String  (HCSP .  H08t_String  (Value) ) ) ; 

—  notice  explicit  Ada  type  converalon 
end  To^Strlng; 

with  Hoat_Character__Support_Pkg; 
separate  (SQL_Char_Plcg) 

function  To_SQL_Char_Hot_Null  (Value  :  String) 
return  SQI._Char_Mot_Null  Is 
package  HCSP  renames  Rost_Character_Support_Plcg; 
begin 

return  (SQL_Char_Not_Null (HCSP . To_Host_Strlng (Value) ) ) ; 

—  notice  Inverse  Ada  type  conversion 
end  To_SQI._Char_Kot_Null; 

Note:  Unlike  the  package  specifications  SQL_St'  ndard  and  SQL_System,  the  remaining  user 
modifications  are  all  to  bodies.  Whereas  modifications  to  the  package  specifications  must  be 
made  before  any  compilations  can  take  place,  the  remaining  modifications  can  be  done  later,  and 
redone,  without  recompilation  effects. 


3.  Compilation  Order 

The  SAME  standard  packages  are  divided  into  groups.  Packages  within  a  group  may  be  com¬ 
piled  in  any  order.  Ail  packages  in  one  group  must  be  compiled  before  compiling  packages  in  the 
next  group.  Notice  that  the  bodies  of  packages  are  distributed  in  separate  fiies  from  those  con¬ 
taining  the  specifications  of  pacages.  These  files  are  named  <package  name>_Body. 

Group  I. 

1 .  SQL_Standard 

2.  SQL_System 

3.  SQL_Exceptions 

Group  II. 

1 .  SQL_Boolean_Pkg 

Group  III. 

1 .  SQL_Char  Pkg 

2.  SQL_ReaLPkg 

3.  SQL_Double_Preasion_Pkg 
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Group  IV. 

1 .  SQL_Communications_Pkg 

2.  SQL_lnt_Pkg 

3.  SQL_Smallint_Pkg 

4.  SQL_Enumeration_Pkg 


Group  V. 

1 .  SQL_Base_Types_Pkg 

2.  To_SQL_Char_Not_Null 

3.  To_String 

4.  3QL_Decima!_Pkg 

Group  VI. 

1 .  SQL_Database_Error_Pkg 
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